home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1999 #3 / Amiga Plus CD - 1999 - No. 3.iso / System / delitracker_ii / developer / include / misc / deliplayer.i next >
Text File  |  1995-06-03  |  14KB  |  389 lines
  1. **
  2. **  $Filename: misc/DeliPlayer.i $
  3. **  $Release: 2.0 $
  4. **  $Revision: 2.15$
  5. **  $Date: 02/06/95$
  6. **
  7. **    Definitions and Macros for creating DeliTracker Player&Genie-modules
  8. **
  9. **    (C) Copyright 1991, 1992, 1993, 1994, 1995 Delirium Softdesign
  10. **        All Rights Reserved
  11. **
  12.  
  13.     IFND    DELITRACKER_PLAYER_I
  14. DELITRACKER_PLAYER_I    SET    1
  15.  
  16.     IFND EXEC_PORTS_I
  17.         INCLUDE "exec/ports.i"
  18.     ENDC
  19.  
  20.     IFND EXEC_TYPES_I
  21.         INCLUDE "exec/types.i"
  22.     ENDC
  23.  
  24.     IFND UTILITY_TAGITEM_I
  25.         INCLUDE "utility/tagitem.i"
  26.     ENDC
  27.  
  28. ;----------------------------------------------------------------------------
  29.  
  30. DELIVERSION    EQU    17            ; Current Version of DeliTracker
  31. DELIREVISION    EQU    4            ; Current Revision of DeliTracker
  32.  
  33.  
  34. ;------------------------ Player Function Offsets ---------------------------
  35.  
  36.  STRUCTURE DeliTrackerPlayer,0
  37.  
  38.     STRUCT    dtp_RTS_code,4            ; RTS for security (private !)
  39.     STRUCT    dtp_ID,8            ; Identifier (private !)
  40.     APTR    dtp_TagArray            ; pointer to TagItem array
  41.     LABEL    dtp_SIZE
  42.  
  43. * The TagItem ID's (ti_Tag values) for the player interface follow.
  44.  
  45. DTP_TagBase    EQU    TAG_USER+"DT"
  46.  
  47.     ENUM    DTP_TagBase            ; TagBase
  48.  
  49.     EITEM    DTP_InternalPlayer        ; obsolete
  50.     EITEM    DTP_CustomPlayer        ; player is a customplayer
  51.  
  52.     EITEM    DTP_RequestDTVersion        ; minimum DeliTracker version needed
  53.     EITEM    DTP_RequestKickVersion        ; minimum KickStart version needed
  54. DTP_RequestV37    EQU    DTP_RequestKickVersion    ; obsolete
  55.  
  56.     EITEM    DTP_PlayerVersion        ; actual player version & revision
  57.     EITEM    DTP_PlayerName            ; name of this player
  58.     EITEM    DTP_Creator            ; misc string
  59.  
  60.     EITEM    DTP_Check1            ; Check Format before loading
  61.     EITEM    DTP_Check2            ; Check Format after file is loaded
  62.     EITEM    DTP_ExtLoad            ; Load additional files
  63.     EITEM    DTP_Interrupt            ; Interrupt routine
  64.     EITEM    DTP_Stop            ; Clear Patterncounter
  65.     EITEM    DTP_Config            ; Config Player
  66.     EITEM    DTP_UserConfig            ; User-Configroutine
  67.     EITEM    DTP_SubSongRange        ; Get min&max subsong number
  68.  
  69.     EITEM    DTP_InitPlayer            ; Initialisize the Player
  70.     EITEM    DTP_EndPlayer            ; Player clean up
  71.     EITEM    DTP_InitSound            ; Soundinitialisation routine
  72.     EITEM    DTP_EndSound            ; End sound
  73.     EITEM    DTP_StartInt            ; Start interrupt
  74.     EITEM    DTP_StopInt            ; Stop interrupt
  75.  
  76.     EITEM    DTP_Volume            ; Set Volume
  77.     EITEM    DTP_Balance            ; Set Balance
  78.     EITEM    DTP_Faster            ; Incease playspeed
  79.     EITEM    DTP_Slower            ; Decrease playspeed
  80.     EITEM    DTP_NextPatt            ; Jump to next pattern
  81.     EITEM    DTP_PrevPatt            ; Jump to previous pattern
  82.     EITEM    DTP_NextSong            ; Play next subsong
  83.     EITEM    DTP_PrevSong            ; Play previous subsong
  84.  
  85.     ;--- functions in revision 14 (distributed as Release 1.35) ---
  86.  
  87.     EITEM    DTP_SubSongTest            ; Test, if given subsong is vaild
  88.  
  89.     ;--- functions in revision 16 (distributed as Release 2.01) ---
  90.  
  91.     EITEM    DTP_NewSubSongRange        ; enhanced replacement for DTP_SubSongRange
  92.  
  93.     EITEM    DTP_DeliBase            ; the address of a pointer where DT
  94.                         ; stores a pointer to the DeliGlobals
  95.  
  96.     EITEM    DTP_Flags            ; misc Flags (see below)
  97.  
  98.     EITEM    DTP_CheckLen            ; Length of the Check Code
  99.  
  100.     EITEM    DTP_Description            ; misc string
  101.  
  102.     EITEM    DTP_Decrunch            ; pointer to Decrunch Code
  103.     EITEM    DTP_Convert            ; pointer to Converter Code
  104.  
  105.     EITEM    DTP_NotePlayer            ; pointer to a NotePlayer Structure
  106.     EITEM    DTP_NoteStruct            ; the address of a pointer to the
  107.                         ; NoteStruct Structure
  108.     EITEM    DTP_NoteInfo            ; a pointer where DT stores a pointer
  109.                         ; to the current NoteStruct Structure
  110.     EITEM    DTP_NoteSignal            ; pointer to NoteSignal code
  111.  
  112.     EITEM    DTP_Process            ; pointer to process entry code
  113.     EITEM    DTP_Priority            ; priority of the process
  114.     EITEM    DTP_StackSize            ; stack size of the process
  115.     EITEM    DTP_MsgPort            ; a pointer where DT stores a pointer
  116.                         ; to a port to send its messages
  117.  
  118.     EITEM    DTP_Appear            ; open your window, if you can
  119.     EITEM    DTP_Disappear            ; go dormant
  120.  
  121.     EITEM    DTP_ModuleName            ; get the name of the current module
  122.     EITEM    DTP_FormatName            ; get the name of the module format
  123.     EITEM    DTP_AuthorName            ; not implemented yet
  124.  
  125.     ;--- functions in revision 17 (distributed as Release 2.07) ---
  126.  
  127.     EITEM    DTP_InitNote            ; NoteStruct initialization
  128.  
  129. *** end of player interface enumeration ***
  130.  
  131.  
  132. ; --- various flags ---------------------------------------------------------
  133.  
  134.     BITDEF    PLY,CUSTOM,0            ; the player is a customplayer
  135.     BITDEF    PLY,SONGEND,1            ; this player supports songend
  136.  
  137.     ;--- flags defined in revision 17 (distributed as Release 2.07) ---
  138.  
  139.     BITDEF    PLY,ANYMEM,2            ; modules of this player don't require chipmem
  140.  
  141.  
  142. ; --- DeliTracker message ---------------------------------------------------
  143.  
  144.    STRUCTURE DeliMessage,MN_SIZE
  145.     ULONG    DTMN_Function            ; function pointer
  146.     ULONG    DTMN_Result            ; store the result here
  147.    LABEL DTMN_SIZE
  148.  
  149.  
  150. ;------------------------------ Player Header -------------------------------
  151. ;
  152. ; Here is the MACRO for creating the player header structure. Use this MACRO !!!
  153.  
  154. PLAYERHEADER    MACRO
  155.     IFC    '\2',''
  156.     moveq    #-1,d0            ; this should return an error
  157.     rts                ; in case someone tried to run it
  158.     ELSE
  159.     bra.w    \2            ; branch to startupcode
  160.     ENDC
  161.     dc.b    'DELIRIUM'        ; identifier
  162.     dc.l    \1            ; ^tagitem array
  163.     ENDM
  164.  
  165.  
  166.     ;------ When a subroutine in the player is called, A5 will contain
  167.     ;------ the pointer to the DeliTrackerGlobals, the only exeption is
  168.     ;------ of course the interrupt routine.
  169.     ;------ The interruptroutine is called every 1/50 sec (via timerint).
  170.  
  171.     ;------ When Check is called, supply d0=0 if the format is ok
  172.     ;------ else d0<>0.
  173.  
  174.     ;------ Check1 is called before loading the complete file, you can
  175.     ;------ check in the first 1024 Bytes of the file. If the file is
  176.     ;------ smaller than 1kB, the remaining space will contain zero.
  177.  
  178.     ;------ Check2 is called after the complete file is loaded, you
  179.     ;------ can use dtg_ChkSize to determine the length of the file.
  180.     ;------ If you supply this tag the file can be crunched.
  181.  
  182.     ;------ ExtLoad: routine for loading additional files (instruments).
  183.     ;------    If successful, you must return d0=0 else d0<>0. In case of
  184.     ;------ an error DeliTracker frees all memory used for this module.
  185.  
  186.     ;------    InitPlayer: Here you should allocate the audio channels.
  187.     ;------ In case the player supports multi-modules, you must set here
  188.     ;------ dtg_SndNum to the minimal subsong number (not necessary if
  189.     ;------ you have supplied a DTP_SubSongRange routine!).
  190.     ;------ If successful, you must return d0=0 else d0<>0.
  191.  
  192.     ;------    EndPlayer: Here you should free the audio channels.
  193.  
  194.     ;------ InitSound: If you want to use the internal interrupt but don't
  195.     ;------ need the default 50 Hz frequency, you can write another timer
  196.     ;------ value into dtg_Timer.
  197.  
  198.     ;------ It is recommended to use DTP_SubSongRange/DTP_SubSongTest
  199.     ;------ instead of DTP_NextSong/DTP_PrevSong.
  200.  
  201.     ;------ Volume usually only copies the values dtg_Volume, dtg_SndLBal
  202.     ;------ and dtg_SndRBal to an internal buffer. The interrupt code has
  203.     ;------ access to this buffer and can set the volume correct.
  204.  
  205.     ;------ CheckLen: This tag is only allowed for players. If you supply
  206.     ;------ this tag, the player will be unloaded by DeliTracker in low
  207.     ;------ memory situations. When needed, it will be loaded again
  208.     ;------ automatically.
  209.  
  210.     ;------ Decrunch: Supply d0=0 if you could decrunch the file else
  211.     ;------ d0<>0.
  212.  
  213.     ;------ Convert: Supply d0=0 if you converted the file to another
  214.     ;------ format, else d0<>0.
  215.  
  216.     ;------ Appear: Supply d0<>0 if the window was already opend, else
  217.     ;------ d0=0.
  218.  
  219.     ;------ Disappear: Supply d0=0 if the window was already closed, else
  220.     ;------ d0<>0.
  221.  
  222.     ;------ ModuleName: This tag is only allowed for players. It contains
  223.     ;------ the address of a pointer to the module name (must be null
  224.     ;------ terminated). The tag is evaluated after the InitPlayer function
  225.     ;------ was called.
  226.  
  227.     ;------ FormatName: This tag is only allowed for convert genies. It
  228.     ;------ contains the address of a pointer to the name of the module
  229.     ;------ format (must be null terminated). The tag is evaluated after
  230.     ;------ the InitPlayer function was called.
  231.  
  232.     ;------ AuthorName: This tag is only allowed for players. It contains
  233.     ;------ the address of a pointer to the authorname (must be null
  234.     ;------ terminated). The tag is evaluated after the InitPlayer function
  235.     ;------ was called.
  236.  
  237.     ;------ Note: the Player can consist of more Hunks. That means you
  238.     ;------ can seperate CHIP DATA form CODE (and you should do this!).
  239.  
  240.  
  241. ;---------------------------- Global Variables ------------------------------
  242.  
  243.  STRUCTURE DeliTrackerGlobals,0
  244.  
  245.     ;------ if you use dtg_AslBase, make sure that
  246.     ;------ DTP_RequestDTVersion is at least 13 !
  247.  
  248.     APTR    dtg_AslBase        ; librarybase don't CloseLibrary()
  249.  
  250.     APTR    dtg_DOSBase        ; librarybase -"-
  251.     APTR    dtg_IntuitionBase    ; librarybase -"-
  252.     APTR    dtg_GfxBase        ; librarybase -"-
  253.     APTR    dtg_GadToolsBase    ; librarybase -"- (NULL for Kick 1.3 and below)
  254.     APTR    dtg_ReservedLibraryBase    ; reserved for future use
  255.  
  256.     APTR    dtg_DirArrayPtr        ; Ptr to the directory of the current module
  257.     APTR    dtg_FileArrayPtr    ; Ptr to the filename of the current module
  258.     APTR    dtg_PathArrayPtr    ; Ptr to PathArray (e.g used in LoadFile())
  259.  
  260.     APTR    dtg_ChkData        ; pointer to the module to be checked
  261.     ULONG    dtg_ChkSize        ; size of the module
  262.  
  263.     UWORD    dtg_SndNum        ; current sound number
  264.     UWORD    dtg_SndVol        ; volume (ranging from 0 to 64)
  265.     UWORD    dtg_SndLBal        ; left volume (ranging from 0 to 64)
  266.     UWORD    dtg_SndRBal        ; right volume (ranging from 0 to 64)
  267.     UWORD    dtg_LED            ; filter (0 if the LED is off)
  268.     UWORD    dtg_Timer        ; timer-value for the CIA-Timers
  269.  
  270.     FPTR    dtg_GetListData        ;
  271.     FPTR    dtg_LoadFile        ;
  272.     FPTR    dtg_CopyDir        ;
  273.     FPTR    dtg_CopyFile        ;
  274.     FPTR    dtg_CopyString        ;
  275.     FPTR    dtg_AudioAlloc        ;
  276.     FPTR    dtg_AudioFree        ;
  277.     FPTR    dtg_StartInt        ;
  278.     FPTR    dtg_StopInt        ;
  279.     FPTR    dtg_SongEnd        ; save to call from interrupt code !
  280.     FPTR    dtg_CutSuffix        ;
  281.  
  282.     ;------ extension in revision 14
  283.  
  284.     FPTR    dtg_SetTimer        ; save to call from interrupt code !
  285.  
  286.     ;------ extension in revision 15
  287.  
  288.     FPTR    dtg_WaitAudioDMA    ; save to call from interrupt code !
  289.  
  290.     ;------ extension in revision 16
  291.  
  292.     FPTR    dtg_LockScreen
  293.     FPTR    dtg_UnlockScreen
  294.     FPTR    dtg_NotePlayer        ; save to call from interrupt code !
  295.     FPTR    dtg_AllocListData
  296.     FPTR    dtg_FreeListData
  297.  
  298.     FPTR    dtg_Reserved1        ; do not use !!!
  299.     FPTR    dtg_Reserved2        ; do not use !!!
  300.     FPTR    dtg_Reserved3        ; do not use !!!
  301.  
  302.     ; There is no dtg_SIZEOF cause ...
  303.  
  304.  
  305.     ;------ GetListData(Num:d0): This function returns the memorylocation
  306.     ;------ of a loaded file in a0 and its size in d0. Num starts with 0
  307.     ;------ (the selected module). Example: GetListData(2) returns the
  308.     ;------ start of the third file loaded (via ExtLoad) in a0 an its size
  309.     ;------ in d0.
  310.  
  311.     ;------ LoadFile(): this function may only be called in the ExtLoad
  312.     ;------ routine. file/pathname must be in dtg_PathArrayPtr then
  313.     ;------ this function will attempt to load the file into CHIPMEM
  314.     ;------ (and DECRUNCH it). If everything went fine, d0 will be zero.
  315.     ;------ If d0 is not zero this indicates an error (e.g. read error,
  316.     ;------ not enough memory, ...).
  317.  
  318.     ;------ CopyDir(): this function copies the pathname at the end
  319.     ;------ of the string in dtg_PathArrayPtr(a5).
  320.  
  321.     ;------ CopyFile(): this function copies the filename at the end
  322.     ;------ of the string in dtg_PathArrayPtr(a5).
  323.  
  324.     ;------ CopyString(Ptr:a0): this function copies the string in a0
  325.     ;------ at the end of the string in dtg_PathArrayPtr(a5).
  326.  
  327.     ;------ AudioAlloc(): this function allocates the audiochannels
  328.     ;------ (only necessary if the player doesn't supply a NoteStruct
  329.     ;------ tag). If d0=0 all is ok, d0<>0 indicates an error.
  330.  
  331.     ;------ AudioFree(): this function frees the audiochannels allocated
  332.     ;------ with AudioAlloc().
  333.  
  334.     ;------ StartInt(): this function starts the timer-interrupt.
  335.  
  336.     ;------ StopInt(): this function stops the timer-interrupt started
  337.     ;------ with StartInt().
  338.  
  339.     ;------ SongEnd(): signal the songend to DeliTracker.
  340.     ;------ This call is guaranteed to preserve all registers.
  341.  
  342.     ;------ CutSuffix(): this function removes the suffix '.xpk' or '.pp'
  343.     ;------ from the string in dtg_PathArrayPtr(a5).
  344.  
  345.     ;------ SetTimer(): programs the CIA-Timer with the value supplied
  346.     ;------ in dtg_Timer(a5). Only useful, if the internal timer-interrupt
  347.     ;------ is used. This call is guaranteed to preserve all registers.
  348.  
  349.     ;------ WaitAudioDMA(): DMA delay wait. Only allowed, if the internal
  350.     ;------ timer-interrupt is used. This call is guaranteed to preserve
  351.     ;------ all registers.
  352.  
  353.     ;------ LockScreen(): this function tries to lock DeliTracker's screen.
  354.     ;------ It returns the screenpointer in d0 or NULL on failure.
  355.  
  356.     ;------ UnlockScreen(): this function unlocks DeliTracker's screen.
  357.     ;------ do not unlock a screen more times than it was locked!
  358.  
  359.     ;------ NotePlayer(): this call plays the notes specified in the
  360.     ;------ current NoteStruct structure. This function call is not allowed
  361.     ;------ if the active player doesn't have a valid NotePlayer structure.
  362.     ;------ do not call this function in interrupt code at interrupt
  363.     ;------ level 5 or higher! This call is guaranteed to preserve
  364.     ;------ all registers.
  365.  
  366.     ;------ AllocListData(Size:d0/Flags:d1): This is the memory allocator
  367.     ;------ for module specific memory to be used by all players and genies.
  368.     ;------ It provides a means of specifying that the allocation should be
  369.     ;------ made in a memory area accessible to the chips, or accessible to
  370.     ;------ shared system memory. If the allocation is successful,
  371.     ;------ DeliTracker will keep track of the new block (GetListData() will
  372.     ;------ return the location and size of this block).
  373.     ;------ byteSize - the size of the desired block in bytes.
  374.     ;------ Flags - the flags are passed through to AllocMem().
  375.     ;------ A pointer to the newly allocated memory block is returned in d0.
  376.     ;------ If there are no free memory regions large enough to satisfy the
  377.     ;------ request, zero will be returned. The pointer must be checked
  378.     ;------ for zero before the memory block may be used!
  379.  
  380.     ;------ FreeListData(MemBlock:a1): Free a region of memory allocated
  381.     ;------ with AllocListData(), returning it to the system pool from which
  382.     ;------ it came.
  383.     ;------ memoryBlock - pointer to the memory block to free, or NULL.
  384.  
  385.  
  386.     ENDC    ; DELITRACKER_PLAYER_I
  387.  
  388.  
  389.